package birdsong.client;

import birdsong.comm.ClientComm;
import birdsong.comm.ServerComm;

/**
 * A Birdsong client should use a {@link birdsong.comm.ClientComm} interface to
 * communicate with the server.
 * 
 * <p>
 * When a client connects to the server, it will first receive one
 * {@link birdsong.comm.ClientSideMessage.Type#CONNECTED CONNECTED} message for
 * each user currently connected to the client. The client thus receives
 * information about other clients currently connected to the server when it
 * connects to be able to maintain a list of users online.
 * 
 * <p>
 * After a client has connected, it can then send Birdsong messages (
 * {@link birdsong.comm.ClientComm#sendBirdsongMessage(String)}), follow
 * requests ({@link birdsong.comm.ClientComm#follow(String)}), and unfollow
 * requests ({@link birdsong.comm.ClientComm#unfollow(String)}) to the server.
 * 
 * <p>
 * The client should use {@link birdsong.comm.ClientComm#getNextMessage()} to
 * receive:
 * <ul>
 * <li>Birdsong messages from other users (type =
 * {@link birdsong.comm.ClientSideMessage.Type#BIRDSONG_MESSAGE
 * BIRDSONG_MESSAGE}),
 * <li>notifications about new followers (type =
 * {@link birdsong.comm.ClientSideMessage.Type#FOLLOWER FOLLOWER})
 * <li>notifications about new unfollowers (type =
 * {@link birdsong.comm.ClientSideMessage.Type#UNFOLLOWER UNFOLLOWER})
 * <li>notifications about new clients online (type =
 * {@link birdsong.comm.ClientSideMessage.Type#CONNECTED CONNECTED })
 * <li>notifications about clients who go offline (type =
 * {@link birdsong.comm.ClientSideMessage.Type#DISCONNECTED DISCONNECTED})
 * </ul>
 * 
 * <p>
 * If a client loses its connection to the server, it will not be following any
 * users nor will it have any followers even if it reconnects.
 * 
 * @author alc
 * @version 1
 * 
 */
public interface BirdsongClient {

    /**
     * Starts the client and only returns when (if ever) the client is stopped.
     * 
     * @param clientComm
     *            the clientComm through which the client should communicate
     *            with the server.
     */

    public void start(ClientComm clientComm);

}
